Overview

This PR addresses issue about z-axis coordinate calculation for 3D reconstruction by adding a new utility function assign_z_coordinates() that systematically assigns z-coordinates to multiple 2D spatial transcriptomics slices.

Problem

Users performing 3D reconstruction from sequential 2D tissue sections previously had no clear guidance or automated method for:

• Determining appropriate z-spacing between slices
• Calculating and assigning z-axis coordinates
• Handling non-uniform sections or missing slices
• Following best practices for 3D model construction

Currently, when 2D data is encountered, Spateo automatically adds zeros for z-coordinates, but there was no documented workflow for properly spacing slices in the z-dimension.

Solution

New Function: assign_z_coordinates()

Added a comprehensive function accessible via st.tl.assign_z_coordinates() or st.align.assign_z_coordinates() that supports three z-spacing strategies:

1. Default/Custom Uniform Spacing

# Default spacing of 1.0
st.tl.assign_z_coordinates(slices, spatial_key="align_spatial")

# Custom uniform spacing
st.tl.assign_z_coordinates(slices, z_spacing=10.0)

2. Tissue Thickness-Based Spacing

# Use known tissue section thickness
st.tl.assign_z_coordinates(slices, tissue_thickness=15.0)  # 15 µm sections

3. Variable Spacing for Non-Uniform Sections

# Handle missing sections or variable spacing
st.tl.assign_z_coordinates(slices, z_spacing=[10.0, 30.0, 10.0])  # Larger gap for missing section

Complete Workflow Example

import spateo as st

# Step 1: Load and align 2D slices (existing functionality)
slices = [slice1, slice2, slice3, slice4]
for i in range(1, len(slices)):
    st.tl.morpho_align(sliceA=slices[i], sliceB=slices[i-1], 
                       spatial_key='spatial', key_added='align_spatial')

# Step 2: Assign z-coordinates (NEW)
st.tl.assign_z_coordinates(slices, spatial_key='align_spatial', 
                           tissue_thickness=15.0)

# Step 3: Visualize 3D model (existing functionality)
st.pl.three_d_multi_plot.multi_models(*slices, spatial_key='align_spatial')

Key Features

• ✅ Flexible spacing strategies: uniform, tissue thickness-based, or variable
• ✅ Handles edge cases: single slices, missing sections, different coordinate systems
• ✅ Preserves data: Original XY coordinates unchanged, option for in-place or copy
• ✅ Well-tested: 8 comprehensive unit tests (all passing)
• ✅ Documented: 561 lines of technical documentation and practical examples
• ✅ Zero breaking changes: Purely additive functionality

Documentation Added

1. Technical Documentation (docs/technicals/3d_reconstruction.md):

   • Understanding z-spacing strategies
   • Complete 3D reconstruction workflow
   • Best practices and recommendations
   • Common pitfalls and troubleshooting
   • Advanced topics (global refinement, coordinate systems)

2. Practical Examples (docs/examples/3d_reconstruction_example.md):

   • Quick start code snippets
   • Complete workflow examples
   • Handling different coordinate systems
   • Dealing with missing sections

Testing

Added 8 comprehensive unit tests in tests/alignment/test_utils.py covering:

• Default uniform spacing
• Custom uniform spacing
• Tissue thickness-based spacing
• Variable spacing
• Z-offset functionality
• In-place vs. copy modification
• XY coordinate preservation
• Single slice handling

All tests verified passing ✓

Files Changed

• spateo/alignment/utils.py (+146 lines) - Core function implementation
• spateo/alignment/__init__.py (+1 line) - Export function
• spateo/align.py (+1 line) - Module integration
• docs/technicals/3d_reconstruction.md (+339 lines) - Technical documentation
• docs/technicals/index.md (+2 lines) - Add to documentation index
• docs/examples/3d_reconstruction_example.md (+203 lines) - Practical examples
• docs/examples/README.md (+18 lines) - Examples directory index
• tests/alignment/test_utils.py (+164 lines) - Comprehensive test suite

Total: 8 files changed, 874 insertions (+)

Impact

This PR provides users with a systematic, flexible, and well-documented approach to z-coordinate assignment for 3D reconstruction, directly addressing the questions raised about:

• ✅ How to determine appropriate z-spacing between slices
• ✅ Whether Spateo provides automatic z-coordinate calculation
• ✅ Best practices for assigning z-values when building 3D models
• ✅ Recommended workflow for 3D reconstruction in Spateo

The implementation follows Spateo's existing patterns and conventions, integrating seamlessly with the current alignment and visualization workflows.

Fixes #348

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.